Динамический QR-код
Оплата по динамическому QR-коду — это один из способов безналичной оплаты, альтернатива платежам совершаемых банковскими картами.
Динамический QR-код создается отдельно под каждую конкретную покупку, поэтому он сразу содержит стоимость покупки и все необходимые для платежа реквизиты. Изменить сумму покупки нельзя.
Для генерации динамического QR-кода необходимо устройство: компьютер, смартфон или терминал. Чтобы провести оплату кассир вводит сумму покупки, QR-код выводится на экране устройства или распечатывается на пречеке, покупатель его сканирует с помощью камеры мобильного телефона или через банковское приложение, подтверждает оплату. Средства мгновенно поступают на счёт продавца.
1. Запрос на регистрацию динамического QR-кода
Метод GetQRCd
a) Описание параметров запроса:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| command | String (an-1…50) | y | Тип запроса. Константа «GetQRCd». |
| TermNo | String (an-20) | y | Уникальный идентификатор терминала. |
| qrcType | String (n-2) | y | Тип запрашиваемого QR-кода — «02». |
| amount | Number | y | Сумма платежа в минорных единицах (копейках). |
| currency | String (ans-3) | y | Код валюты (для рублей должен передаваться «RUB»). |
| OrderNumber | String (ans-1000) | o | Номер заказа. В параметре должны передаваться только английские буквы и/или арабские цифры, подчеркивание, тире, иначе инициатору будет направлена ошибка. |
| width | String | o | Ширина картинки QR-кода (только числовое значение). |
| height | String | o | Высота картинки QR-кода (только числовое значение). |
| paymentPurpose | String (ans-140) | o | Назначение платежа. |
| messageID | String (an-1…1024) | o | Уникальный идентификатор сообщения, GUID. Только латинские символы! |
| qrTtl | String (an-1…6) | o | Срок жизни Платежной ссылки СБП в минутах. Минимальное допустимое значение — «1». Максимальное допустимое значение — «129 600» (90 дней). Рекомендация: устанавливать срок жизни Платежной ссылки СБП не менее «5» минут. Если поле «qrTtl» не передано в запросе, будет использовано значение по умолчанию — «4 320» минут (3 суток). |
| queryData.notificationUrl | String (ans-512) | o | Полный URL для получения уведомления о финальном статусе оплаты QR-кода. Если параметр отсутствует, уведомление не производится. |
| redirectUrl | String (ans-1024) | о | Содержит ссылку для автоматического возврата в приложение или на сайт ТСП. Допускаются только символы в кодировке ASCII. Формат должен соответствовать правилам кодировки URL. Если все же требуется использовать в redirectUrl кириллические символы, необходимо перекодировать их в соответствующий ASCII код, используя percent-encoded octets согласно RFC3986. |
Блок для внесения дополнительных идентификаторов ТСП
| Код ключа | Тип данных | required | Назначение | |
|---|---|---|---|---|
| extJsonParams | Object | o | Блок дополнительных идентификаторов. В блоке можно передать до 10 ключей с необходимыми ТСП значениями.* | |
| JsonParam1 | String (ans-250) | o | Дополнительный идентификатор ТСП | |
| JsonParam2 | String (ans-250) | o | Дополнительный идентификатор ТСП | |
| ... | ... | ... | ... | |
| JsonParam10 | String (ans-250) | o | Дополнительный идентификатор ТСП |
Если требуется сформировать динамический QR-код для привязки дополнительного счёта Плательщика в том же Банке
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| subscriptionServiceId | String (32) | o | Идентификатор привязки. Обязательно при наличии subscriptionServiceName, т. к. параметры subscriptionServiceId и subscriptionServiceName могут быть переданы только вместе. При получении параметров subscriptionServiceId и subscriptionServiceName Банк Плательщика должен использовать их в ходе проверки данных привязки счёта на уникальность. |
| subscriptionServiceName | String (70) | o | Наименование привязки. Обязательно при наличии subscriptionServiceId, т. к. параметры subscriptionServiceId и subscriptionServiceName могут быть переданы только вместе. При получении параметров subscriptionServiceId и subscriptionServiceName Банк Плательщика должен использовать их в ходе проверки данных привязки счёта на уникальность. |
Если требуется сформировать динамический QR-код под определенного Плательщика, то необходимо использовать следующие поля:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| queryData.SenderFIO | String (an-140) | o | Фамилия, Имя и Отчество Плательщика (не является регистрозависимым) |
| queryData.SenderID | String (an-11.13) | o | Идентификатор Плательщика (номер телефона Плательщика — 0079123456789) |
| queryData.SenderBankBIC | String (n-9) | o | БИК Банка Плательщика |
* Блок для передачи дополнительных идентификаторов ТСП в ежедневные реестры СБП. Функционал потребует дополнительной настройки реестра по СБП. Для настройки необходимо обратиться в Банк по адресу acquiring@alfabank.ru
b) Примерный формат запроса:
1{ 2 "command":"GetQRCd", 3 "TermNo":"90080567 ", 4 "qrTtl":"5", 5 "amount":"10000", 6 "currency":"RUB", 7 "qrcType":"02", 8 "width":"600", 9 "height":"600", 10 "paymentPurpose":"Назаначение платежа", 11 "OrderNumber":"FYI123456", 12 "subscriptionServiceId":"3842ca282aea11e88feca860b60304d5", 13 "subscriptionServiceName":"Подписка на онлайн-кинотеатр", 14 "messageID":"f9aa54ff-a615-44b8-aa6c-acab655c89f8", 15 "redirectUrl": "https://alfabank.ru/sme/payservice/sbp/", 16 "extJsonParams": 17 { 18 "JsonParam1":"Value", 19 "JsonParam2":"Value", 20 "JsonParam3":"Value", 21 "JsonParam4":"Value", 22 "JsonParam5":"Value", 23 "JsonParam6":"Value", 24 "JsonParam7":"Value", 25 "JsonParam8":"Value", 26 "JsonParam9":"Value", 27 "JsonParam10":"Value" 28 }, 29 "queryData": 30 { 31 "notificationUrl":"https://sbp-payments", 32 "SenderFIO":"Иванов|Иван|Иванович", 33 "SenderID":"0079123456789", 34 "SenderBankBIC":"44525593" 35 } 36}
c) Описание параметров ответа:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| ErrorCode | String (an-20) | y | Код ответа*. |
| TermNo | String (an-20) | y | Уникальный идентификатор терминала. |
| image | String (an) Длинна зависит от формата, порядок 7000 символов. | y
| Изображение QR-кода содержит энкодированный BASE64 файл изображения QR-кода 300×300 pix формата .png. |
| message | String (ans-1024) | y | Расшифровка кода ответа**. |
| messageID | String (ans-1024) | o | Уникальный идентификатор сообщения, GUID. Значение параметра возвращается в случае, если оно указано в запросе. |
| payload | String (1…999) | y | Платежная ссылка***. |
| payrrn | String (n-12) | y | Референсный идентификатор запроса в системе Банка. |
| qrcId | String (an-32) | y | Идентификатор QR-кода. |
| status | String (n-7) | y | Статус регистрации Платежной ссылки СБП. |
*, ** Таблица возможных кодов ответа приведена в приложении 2.
*** Формат payload может быть двух видов:
- https://qr.nspk.ru/AD100026KQ0ESJBV8OFPCG0U9K1H52UM
d) Примерный формат ответа:
- •
200 OK
1{ 2 "ErrorCode": 0, 3 "TermNo": 90080567, 4 "image":"iVBORw0KGgoAAAANSUhEUgAAghjysAAAAgjjafggkqqBEoAAARKCAIAAAQA/w……………..................YIAI", 5 "message": "OK", 6 "messageID": "f9aa54ff-a615-44b8-aa6c-acab655c89f8", 7 "payload": "https://qr.nspk.ru/AD100026KQ0ESJBV8OFPCG0U9K1H52UM", 8 "payrrn": "000000022154", 9 "qrcId": "AD100026KQ0ESJBV8OFPCG0U9K1H52UM", 10 "status": "CREATED" 11 }
Примечание: текстовые данные передаются в формате urlencoded.
- •
400 Bad Request { "ErrorCode":"Код ответа", "message":"Расшифровка кода ответа" }
2. Запрос статуса оплаты по динамическому QR-коду
Запрос статуса GetQRCstatus направляется кассой/терминалом ТСП в Банк для получения статуса Операции оплаты выпущенного ранее QR-кода. В ответе платежный шлюз Банка возвращает результат обработки Операции оплаты на стороне Банка.
Запрос статуса направляется не ранее, чем через 10 секунд после формирования QR-кода и не чаще чем каждые 3 секунды.
Успешный ответ на запрос статуса можно получить в течении 30 дней после совершения оплаты по данному QR-коду.
В случае, если срок хранения данных истек, то в ответе на запрос вернется:
{ "ErrorCode": 999, "message":"Неизвестный код проблемы 999RQ05014" }
Метод GetQRCstatus
- •
Описание параметров запроса:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| command | String (an-1…50) | y | Тип запроса. Константа «GetQRCstatus». |
| TermNo | String (an-20) | y | Уникальный идентификатор терминала. |
| qrcId | String (an-32) | y/o | Идентификатор QR-кода (обязательно, если не передан «payrrn»). |
| payrrn | String (n-12) | y/o | Референсный идентификатор запроса в системе Банка (обязательно, если не передан «qrcId „). |
| messageID | String (ans-1024) | o | Уникальный идентификатор сообщения, GUID. Только латинские символы! |
- •
Примерный формат запроса:
{ "command":"GetQRCstatus", "TermNo":"90080567", "qrcId":"AD100026KQ0ESJBV8OFPCG0U9K1H52UM", "payrrn":"000000022154", "messageID": "message" }
- •
Описание параметров ответа:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| ErrorCode | String (an-20) | y | Код ответа*. |
| message | String (ans-1024) | y | Расшифровка кода ответа**. |
| qrcId | String (an-32) | y | Идентификатор QR-кода. |
| status | String(an-10) | y | Статус оплаты QR-кода в НСПК***. Возможные значения: 1. ACWP — ACCEPTED операция завершена успешно; 2. RJCT — REJECTED операция отклонена; 3. NTST — NOT_STARTED операции по QR коду не существует; 4. RCVD — RECEIVED операция в обработке. При оплате по Цифровом рублю: 1. ENDD — платёж с расчётами в ЦР обработан, но результат выполнения неизвестен (успех или отказ) 2. ACDR — передаётся статус (аналог ACWP при оплате СБП C2B), если есть уведомление от ПлЦР об плате. |
| trxId | String (an-32) | y | Уникальный идентификатор платежа в НСПК. |
| trxDT | String (n-14) | y | Дата и время платежа по Гринвичу. Формат — ГГГГММДДччммсс. |
| payrrn | String (n-12) | y | Референсный идентификатор запроса в системе Банка. |
| CreditDatePos | String (ans 1-256) | y | Дата операции, установленная Банком Получателя (ГГГГММДД) |
| TermNo | String (an-20) | y | Уникальный идентификатор терминала. |
| amount | Number | y | Сумма платежа в минорных единицах (копейках). |
| currency | String (ans-3) | o | Код валюты (для рублей должен передаваться «RUB»). |
| Url | String (ans 1-512) | o | Полный URL для получения уведомления ТСП о финальном статусе оплаты QR-кода. Значение параметра, переданного при регистрации динамического QR-кода в поле «queryData.notificationUrl». |
| payerId | String (n-13) | y | Идентификатор плательщика (маскированный номер телефона плательщика). |
| Kzo | String (ans 1-128) | o | Контрольное Значение Операции СБП. Присутствует при условии, что Операция СБП C2B по запрашиваемому qrcId завершена успешно (параметр «status» ="ACWP»). |
| messageID | String (ans-1024) | o | Уникальный идентификатор сообщения, GUID. Значение параметра возвращается в случае, если оно указано в запросе. |
| merchantId | String (12) | o | ID мерчанта (ТСТ) в Банке |
*, ** Таблица возможных кодов ответа приведена в приложении 2.
**Примечание: **
- •
Успешно оплаченным считается только QR-код, для которого получен «status» = «ACWP» с идентификатором платежа «trxId» и «ErrorCode» = 0;
- •
В случае если получен «status» = «NTST» — означает необходимость повтора запроса до получения одного из финальных статусов «ACWP» или «RJCT»;
- •
Получение «status» = «RJCT» означает отказ в оплате данного QR-кода.
— Примерный формат ответа:
- •
200 OK
1{ 2 "ErrorCode": 0, 3 "message": "OK", 4 "qrcId": "AD100026KQ0ESJBV8OFPCG0U9K1H52UM", 5 "status": "ACWP", 6 "trxId": "A3013090427361010000057B3DA2D4A7", 7 "trxDT": "20230113090427", 8 "payrrn": "000000022154", 9 "CreditDatePos": "20230113", 10 "TermNo": 90080567, 11 "amount": 10000, 12 "currency": "RUB", 13 "Url":"https://sbp-payments", 14 "payerId": "*********1234", 15 "kzo": "212b906a810f2562fd88e145199b30f4b4ea5c7cd7d0261236a73a6152f07f56b7feb915712a055522ee9b763b505c02d560e59ec2f39700340d114b5d82c429", 16 "messageID": "message", 17 "merchantId": "MB0000009603" 18 }
**Примечание: **
- •
Текстовые данные передаются в формате urlencoded.
- •
В поле " trxDT» содержится дата и время транзакции на ПШ Банка в формате ГГГГММДДччммсс.
В случае получения значения trxId = null необходимо повторить запрос. Отсутствие значения означает, что в СБП еще нет успешного перевода с оплатой QR-кода с соответствующим идентификатором.
- •
400 Bad Request
{ "ErrorCode":"Код ответа", "message":"Расшифровка кода ответа" }
3. Нотификация ТСП о финальном статусе оплаты по динамическому QR-коду
Запрос отправляется из ПШ Банка во внутреннюю систему ТСП на URL адрес, указанный в параметре «queryData.notificationUrl» при направлении запроса «GetQRCd».
Метод «qrc/notification»
a) Описание параметров запроса:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| command | String (an-1...50) | y | Тип запроса. Константа «qrc/notification» |
| qrcId | String (an-32) | y | Идентификатор QR-кода. |
| trxId | String (an-32) | y | Уникальный идентификатор платежа в НСПК. |
| status | String (an-10) | y | Статус оплаты QR-кода в НСПК. Возможные значения: — ACWP — ACCEPTED операция завершена успешно; — RJCT — REJECTED операция отклонена. |
| amount | Number | y | Сумма платежа в минорных единицах (копейках) |
| timestamp | YYYY-MMDDThh: mm: ss[.SSS] или YYYY-MMDDThh: mm: ss[.SSSZ] | y | Метка времени НСПК по Гринвичу (GMT). |
| payerId | String (n-13) | y | Идентификатор плательщика (маскированный номер телефона плательщика). |
| kzo | String (ans 1-128) | o | Контрольное Значение Операции СБП. Формируется ОПКЦ СБП. Присутствует при условии, что Операция СБП C2B по запрашиваемому qrcId завершена успешно (параметр "status" ="ACWP"). |
| payrrn | String (n-12) | y | Референсный идентификатор запроса в системе Банка. |
| TermNo | String (an-20) | Y | Уникальный идентификатор терминала. |
| CreditDatePos | String (ans 1-256) | o | Дата операции, установленная Банком Получателя в ходе обработки уведомления НСПК . |
b) Примерный формат запроса:
1{ 2 "command":"qrc/notification", 3 "qrcId":"AD100026KQ0ESJBV8OFPCG0U9K1H52UM", 4 "trxId":"A3013090427361010000057B3DA2D4A7", 5 "status":"ACWP", 6 "amount":"10000", 7 "timestamp":"2022-10-27T14:33:49.000Z ", 8 "payerId":"*********1779", 9 "kzo":"580d2f38370f378db5915c047ba7b72014327ce455caa927b2488f224926daac85e82984c889d66e79dad8039ccdefd749d4af59d357bf5422a982b5a8f498ed", 10 "payrrn":"000000022154", 11 "TermNo":"90080567", 12 "CreditDatePos":"20221027" 13}
c) ВС ТСП отвечает http-кодом «200» — успешное получение нотификации, или ошибкой.
В настоящий момент ответ ВС не обрабатывается шлюзом Агента ТСП. Обработка ответов ТСП находится в разработке.
В случае добавления со стороны НСПК дополнительных параметров уведомления, система, принимающая их от шлюза Альфа-Банка, не должна рассматривать такие неожиданные параметры как ошибочный запрос.
4. Запрос проведения возврата по успешной оплате по динамическому QR-коду
Возврат по СБП состоит из 2х последовательных запросов:
- •
GetQRCreversalData — проверка возможности проведения возврата;
- •
QRCreversal — выполнение непосредственно самого возврата.
В случае если ТСП инициирует выполнение повторных операций СБП B2C по одной и той же операции СБП C2B, то допускается не более 5 (пяти) попыток выполнения повторных операций СБП B2C в течение одного операционного дня.
Возврат в один этап. При направлении запроса «QRCReversal», с заполненным полем messageID будет произведен возврат в один этап без вызова на стороне ТСП метода «GetQRCReversalData»
4.1. Запрос возможности проведения возврата
Запрос GetQRCreversalData направляется ТСП в Банк для проверки возможности возврата по ранее оплаченному QR-коду и получения данных плательщика.
Метод GetQRCreversalData
a) Описание параметров запроса:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| command | String (an-1…50) | y | Тип запроса. Константа «GetQRCreversalData». |
| TermNo | String (an-20) | y | Уникальный идентификатор терминала. |
| qrcId | String (an-32) | y/o | Идентификатор QR-кода (обязательно, если не передан «payrrn» или «trxId»). |
| payrrn | String (n-12) | y/o | Референсный идентификатор запроса в системе Банка (обязательно, если не передан «qrcId» или «trxId»). |
| trxId | String (an-32) | y/o | Уникальный идентификатор платежа в НСПК (обязательно, если не передан «qrcId» или «payrrn»). |
| trxDT | String (n-14) | o | Дата и время отменяемого платежа. |
| amount | Number | o | Сумма возврата в минорных единицах (копейках). Если сумма возврата не передана, то значение будет принято значению суммы оплаты за минусом уже совершенных возвратов. |
| currency | String (ans-3) | o | Код валюты (для рублей должен передаваться «RUB»). В случае пустого значения валюта будет взята из данных об оплате. |
| messageID | String (ans-1024) | o | Уникальный идентификатор сообщения, GUID. Только латинские символы! |
| ReturnRestAmount | Boolean | o | Проверка доступного остатка для совершения возврата. |
Примечание:
- •
Для поиска оригинальной транзакции обязательным является один из параметров: «qrcId», «payrrn» или «trxId»;
- •
Терминалы с подключенным сканером и распознаванием QR-кодов могут получить «qrcId», распарсив строку QR-кода с чека оплаты покупки. Формат строки соответствует полю «payload».
b) Примерный формат запроса:
1{ 2 "command":"GetQRCreversalData", 3 "TermNo":"90080567", 4 "qrcId":"AS1000670LSS7DN18SJQDNP4B05KLJL2", 5 "payrrn":"000063441405", 6 "trxId":"X1A2S3D5F6G7H8J9K0C4S5C6D7V5D1K2", 7 "trxDT":"20230313052005", 8 "amount":"10000", 9 "currency":"RUB", 10 "messageID":"f9aa54ff-a615-44b8-aa6c-acab655c89f8", 11 "ReturnRestAmount":true 12}
c) Описание параметров ответа:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| ErrorCode | String (an-20) | y | Код ответа*. |
| TermNo | String (an-20) | y | Уникальный идентификатор терминала. |
| message | String (ans-1024) | y | Расшифровка кода ответа**. |
| messageID | String (ans-1024) | o | Уникальный идентификатор сообщения, GUID. Только латинские символы! |
| payerBnkBIC | String (n-9) | y | БИК банка получателя. |
| payerBnkName | String (an-50) | y | Наименование банка получателя |
| payerId | String (n-13) | y | Идентификатор получателя (маскированный номер телефона получателя). |
| payerPam | String (ans 1…140) | y | PAM получателя |
| payrrn | String (n-12) | y | Референсный идентификатор запроса в системе Банка |
| qrcId | String (an-32) | y | Идентификатор QR-кода |
| trxDT | String (n-14) | y | Дата и время платежа по Гринвичу (GMT). Формат времени — ГГГГММДДччммсс. |
| trxId | String (an-32) | y | Уникальный идентификатор платежа в НСПК. |
| restAmount | Number (с двумя знаками после точки) | o | Сумма доступного остатка к возврату. Если в запросе передано значение "ReturnRestAmount" : true, то в ответе должен присутствовать параметр RestAmount, содержащий сумму доступного к возврату остатка по операции покупки с TrxId, указанном в запросе. |
*, ** Таблица возможных кодов ответа приведена в приложении 2.
d) Примерный формат ответа:
- •
200 OK
1{ 2 "ErrorCode": 0, 3 "TermNo": 90080567, 4 "message": "OK", 5 "payerBnkBIC": "044525593", 6 "payerBnkName": "Альфа-Банк", 7 "payerId": "*1234", 8 "payerPam": "ФСИ", 9 "payrrn": "000063441405", 10 "qrcId": "AS1000670LSS7DN18SJQDNP4B05KLJL2", 11 "trxDT": 20200728114531, 12 "trxId": "X1A2S3D5F6G7H8J9K0C4S5C6D7V5D1K2", 13 "restAmount":"99.87" 14 }
Примечание:
- •
Текстовые данные передаются в формате urlencoded;
- •
В случае получения «message»: «Получен отказ на запрос возврата. Статус Recall, ErrDebetMerchant: KSM0284 Invalid special condition KSM0284» необходимо проверить счёт ТСП. Он должен быть положительным и без ограничений.
- •
400 Bad Request
{ "ErrorCode":"Код ответа", "message":"Расшифровка кода ответа" }
4.2. Запрос возврата оплаты QR-кода
Запрос QRCreversal направляется ТСП в Банк для возврата по ранее произведенной оплате QR. Возврат производится только на счет плательщика, после проверки возможности возврата (метод GetQRCreversalData).
Метод QRCreversal
a) Описание параметров запроса:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| command | String (an-1…50) | y | Тип запроса. Константа «QRCreversal». |
| TermNo | String (an-20) | y | Уникальный идентификатор терминала. |
| qrcId | String (an-32) | y/o | Идентификатор QR-кода (обязательно, если не передан «payrrn» или «trxId»). |
| payrrn | String (n-12) | y/o | Референсный идентификатор запроса в системе Банка (обязательно, если не передан «qrcId» или «trxId»). |
| trxId | String (an-32) | y/o | Уникальный идентификатор платежа в НСПК (обязательно, если не передан «qrcId» или «payrrn»). |
| trxDT | String (n-14) | o | Дата и время отменяемого платежа. |
| amount | Number | o | Сумма возврата в минорных единицах (копейках). Если сумма возврата не передана, то значение будет принято значению суммы оплаты за минусом уже совершенных возвратов. |
| currency | String (ans-3) | o | Код валюты (для рублей должен передаваться «RUB»). В случае пустого значения валюта будет взята из данных об оплате. |
| messageID | String (an-1…50) | y/o | Уникальный идентификатор сообщения, GUID из сообщения «GetQRCreversalData». Обязательно если было указано в запросе GetQRCreversalData*. |
| queryData.notificationUrl | String (ans-512) | o | Полный URL для получения уведомления о финальном статусе возврата QR-кода. Уведомление не производится в случае пустого значения. |
| ReturnRestAmount | Boolean | o | Проверка доступного остатка для совершения возврата. |
Блок для внесения дополнительных идентификаторов ТСП
| Код ключа | Тип данных | required | Назначение | |
|---|---|---|---|---|
| extJsonParams | Object | o | Блок дополнительных идентификаторов. В блоке можно передать до 10 ключей с необходимыми ТСП значениями.** | |
| JsonParam1 | String (ans-250) | o | Дополнительный идентификатор ТСП | |
| JsonParam2 | String (ans-250) | o | Дополнительный идентификатор ТСП | |
| ... | ... | ... | ... | |
| JsonParam10 | String (ans-250) | o | Дополнительный идентификатор ТСП |
* messageID — необходимо передавать точное значение, которые было указано в ответе на запрос GetQRCreversalData. Если значение изменилось, необходимо повторно создать запрос GetQRCreversalData с указанием messageID и затем использовать полученный GUID при запросе на возврат.
** Блок для передачи дополнительных идентификаторов ТСП в ежедневные реестры СБП. Функционал потребует дополнительной настройки реестра по СБП. Для настройки необходимо обратиться в Банк по адресу acquiring@alfabank.ru
Примечание: Для поиска оригинальной транзакции обязательным является один из параметров: «qrcId», «payrrn» или «trxId».
b) Примерный формат запроса:
1{ 2 "command":"QRCreversal", 3 "TermNo":"90080567", 4 "qrcId":"AS1000670LSS7DN18SJQDNP4B05KLJL2", 5 "payrrn":"000063441405", 6 "trxId":"X1A2S3D5F6G7H8J9K0C4S5C6D7V5D1K2", 7 "trxDT":"20230313052005", 8 "amount":"10000", 9 "currency":"RUB", 10 "messageID":"f9aa54ff-a615-44b8-aa6c-acab655c89f8", 11 "extJsonParams": 12 { 13 "JsonParam1":"Value", 14 "JsonParam2":"Value", 15 "JsonParam3":"Value", 16 "JsonParam4":"Value", 17 "JsonParam5":"Value", 18 "JsonParam6":"Value", 19 "JsonParam7":"Value", 20 "JsonParam8":"Value", 21 "JsonParam9":"Value", 22 "JsonParam10":"Value" 23 }, 24 "queryData": 25 { 26 "notificationUrl":"http://sbp-refunds/" 27 }, 28 "ReturnRestAmount": true 29 }
c) Описание параметров ответа:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| ErrorCode | String (an-20) | y | Код ответа*. |
| TermNo | String (an-20) | y | Уникальный идентификатор терминала. |
| amount | Number | y | Сумма платежа в минорных единицах (копейках). |
| currency | String (ans-3) | y | Код валюты (для рублей должен передаваться «RUB»). |
| message | String (ans-1024) | y | Расшифровка кода ответа**. |
| messageID | String (ans-1024) | o | Уникальный идентификатор сообщения, GUID. Только латинские символы! |
| trxDT | String(n-14) | y | Дата и время операции возврата (ГГГГММДДччммсс). |
| trxId | String(an-32) | y | Уникальный идентификатор операции возврата в НСПК. |
| payrrn | String (n-12) | y | Референсный идентификатор запроса в системе Банка. |
| restAmount | Number (с двумя знаками после точки) | o | Сумма доступного остатка к возврату. Если в запросе передано значение "ReturnRestAmount" : true, то в ответе должен присутствовать параметр RestAmount, содержащий сумму доступного к возврату остатка по операции покупки с TrxId, указанном в запросе. |
*, ** Таблица возможных кодов ответа приведена в приложении 2.
d) Примерный формат ответа:
- •
200 OK
1{ 2 "ErrorCode": 0, 3 "TermNo": 90080567, 4 "amount": 10000, 5 "currency": "RUB", 6 "message": "%u0412%u043E%u0437%u0432%u0440%u0430%u0442%20%u043F%u0440%u043E%u0432%u0435%u0434%u0435%u043D", 7 "messageID":"message" 8 "payrrn": "000063441405", 9 "trxDT": 20230624143642, 10 "trxId": "A3024113609260070000086B8426B817", 11 "restAmount": "99.87" 12 }
Примечание: текстовые данные передаются в формате urlencoded.
- •
400 Bad Request
{ "ErrorCode":"Код ответа", "message":"Расшифровка кода ответа" }
5. Запрос статуса возврата СБП (B2C)
Метод «GetQRCreversalStatus» необходим ТСП для уточнения статуса операции B2C (метод QRCreversal).
В запросе «GetQRCreversalStatus» обязательно должна быть передана пара параметров:
«payrrn» или «originalTrxId» Один из параметров «payrrn» или «originalTrxId» используется для нахождения исходного платежа C2B.
«trxId» или «messageID». Один из параметров «trxId» или «messageID» используется для нахождения операции возврата B2C, по которому требуется уточнить статус.
Метод «GetQRCreversalStatus»
a) Описание параметров запроса:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| command | String (an-1…50) | y | Тип запроса. Константа «GetQRCreversalStatus». |
| TermNo | String (an-20) | y | Уникальный идентификатор терминала. |
| payrrn | String (n-12) | y/o (обязательно, если не передан параметр «originalTrxId») | Значение параметра «payrrn» из запроса «QRCreversal». |
| originalTrxId | String (an-32) | y/o (обязательно, если не передан параметр «payrrn») | Идентификатор исходной Операции СБП C2B. |
| trxId | String (an-32) | y/o (обязательно, если не передан messageID,) | Уникальный идентификатор операции возврата в НСПК. |
| messageID | String (ans-1…1024) | y/o (обязательно, если не передан trxId) | Значение параметра «messageID» из запроса «QRCreversal». |
b) Примерный формат запроса:
{ "command":"GetQRCreversalStatus", "TermNo":"90080567", "payrrn":"000063441405", "originalTrxId":"X1A2S3D5F6G7H8J9K0C4S5C6D7V5D1K2", "trxId":"A3024113609260070000086B8426B817", "messageID":"message" }
c) Описание параметров ответа:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| ErrorCode | String (an-20) | y | Код ошибки*. |
| TermNo | String (an-20) | y | Уникальный идентификатор терминала. |
| Url | String (ans 1-512) | o | Полный URL получения уведомления для ТСП — значение параметра, переданного при запросе возврата QRCreversal (queryData.notificationUrl). |
| amount | Number | y | Сумма Операции СБП в копейках. Целое, положительное число. Валюта операции — рубли РФ. |
| message | String (ans-1024) | y | Описание результата выполнения запроса**. |
| messageID | String (ans-1024) | o | Значение параметра «messageID» из запроса «QRCreversal». |
| originalQrcId | String (an-32) | y | Идентификатор зарегистрированной Платежной ссылки СБП, по которому была выполнена исходная Операция СБП C2B. |
| originalTrxId | String (an-32) | y | Идентификатор исходной Операции СБП C2B. |
| payerId | String (an-13) | y | Маскированный номер телефона Клиента-Получателя (Плательщика в исходной Операции C2B, кому делается возврат). |
| status | String (an-4) | y | Статус операции возврата СБП (B2C): ACWP — ACCEPTED операция завершена успешно; RJCT — REJECTED операция отклонена; NTST — Статус операции неизвестен. |
| trxDT | String (n-14) | y | Дата и время выполнения Операции СБП B2C по сценарию «Возврат по Операции СБП C2B» (ГГГГММДДччммсс). |
| trxId | String (an-32) | y | Уникальный идентификатор операции возврата в НСПК. |
*, ** Таблица возможных кодов ответа приведена в приложении 2.
d) Примерный формат ответа:
- •
200 ОК
1{ 2 "ErrorCode": 0, 3 "TermNo": 90080567, 4 "amount": 10000, 5 "message": "OK", 6 "messageID": "message" 7 "originalQrcId": "AS1000670LSS7DN18SJQDNP4B05KLJL2", 8 "originalTrxId": "X1A2S3D5F6G7H8J9K0C4S5C6D7V5D1K2", 9 "payerId": "*********1234", 10 "status": "ACWP", 11 "trxDT": 20230624143642, 12 "trxId": "A3024113609260070000086B8426B817" 13}
Примечание: текстовые данные передаются в формате urlencoded.
- •
400 Bad Request
{ "ErrorCode":"Код ответа", "message":"Расшифровка кода ответа" }
6. Запрос истории возвратов по определённой транзакции СБП C2B
Запрос позволяет ТСП проверить все совершённые возвраты по определённой транзакции СБП C2B.
В ответе на запрос возвращаются как успешные, так и неуспешные попытки возвратов.
Метод GetQRCreversalHistory
a) Описание параметров запроса:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| command | String (an-1…50) | y | Тип запроса. Константа «GetQRCreversalHistory» |
| TermNo | String (an-20) | y | Уникальный идентификатор терминала |
| payrrn | String (n-12) | y | Референсный идентификатор запроса в системе Банка |
b) Примерный формат запроса:
{ "command":"GetQRCreversalHistory", "TermNo":"90080567", "payrrn":"000000002212" }
c) Описание параметров ответа:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| ErrorCode | String (an-20) | y | Код ответа* |
| message | String (ans-1024) | y | Расшифровка кода ответа** |
| Refunds | Array | y | Массив объектов, содержащих информацию о возвратах по платежу, указанному в payrrn входящего запроса. При отсутствии возвратов, будет возвращён ответ с сообщением – «По данной оплате возвраты не найдены» |
| refunds.TermNo | String (an-20) | y | Уникальный идентификатор терминала |
| refunds.amount | Number | y | Сумма Операции СБП B2C (возврат) в копейках. Целое, положительное число. Валюта операции – рубли РФ |
| refunds.originalQrcId | String (an-32) | y | Идентификатор зарегистрированной Платёжной ссылки СБП (QR-кода), по которому была выполнена исходная Операция оплаты СБП C2B |
| refunds.originalTrxId | String (an-32) | y | Идентификатор исходной Операции СБП C2B в НСПК |
| refunds.payerId | String (an-15) | y | Маскированный номер телефона Клиента-Получателя (Плательщика в исходной Операции C2B, кому делается возврат) |
| refunds.status | String (an-4) | y | Статус операции возврата СБП (B2C): 1. ACWP — ACCEPTED возврат успешно выполнен 2. RJCT — REJECTED возврат отклонён 3. NTST — NOT_STARTED возврат не инициирован (получен успешный ответ на запрос GetQRCreversalData, но не инициирован запрос QRCreversal) |
| refunds.trxId | String (an-32) | y | Идентификатор Операции возврата СБП B2C по сценарию «Возврат по Операции СБП C2B» |
| refunds.trxDT | String (n-4) | y | Дата и время выполнения Операции возврата СБП B2C по сценарию «Возврат по Операции СБП C2B». Формат: ГГГГММДДччммсс, UTC +0 |
*, ** Таблица возможных кодов ответа приведена в приложении 2.
d) Примерный формат ответа «ACWP» и «RJCT»:
- •
200 ОК
1{ 2 "ErrorCode": 0, 3 "message": "OK", 4 "refunds": [ 5 { 6 "TermNo": 90080567, 7 "amount": 10000, 8 "originalQrcId": "AS1F004F30VC6B4A9GRBENS0HI6LGRJM", 9 "originalTrxId": "B51390819586020Z0000120011510503", 10 "payerId": "*********1234", 11 "status": "ACWP", 12 "trxDT": 20250519082345, 13 "trxId": "B51390823097450W0000180011510503" 14 }, 15 { 16 "TermNo": 90080567, 17 "amount": 10000, 18 "originalQrcId": "AS1F004F30VC6B4A9GRBENS0HI6LGRJM", 19 "originalTrxId": "B51390819586020Z0000120011510503", 20 "payerId": "*********1234", 21 "status": "RJCT", 22 "trxDT": 20250519083836, 23 "trxId": "A4327120041167130000020011381101" 24 } 25 ] 26 }
- •
400 Bad Request
{ "ErrorCode":"Код ответа", "message":"Расшифровка кода ответа" }
e) Примерный формат ответа «NTST»:
- •
200 ОК
1{ 2 "ErrorCode": 0, 3 "message": "OK", 4 "refunds": [ 5 { 6 "TermNo": 90080567, 7 "amount": 10000, 8 "originalQrcId": "AS1F004F30VC6B4A9GRBENS0HI6LGRJM", 9 "originalTrxId": "B51390819586020Z0000120011510503", 10 "payerId": "*********1234", 11 "status": "NTST", 12 "trxId": "B51390835362750D0000100011510503" 13 } 14 ] 15 }
- •
400 Bad Request
{ "ErrorCode":"Код ответа", "message":"Расшифровка кода ответа" }
f) Примерный формат ответа при отсутствии возвратов по транзакции СБП C2B:
- •
200 OK
{ "ErrorCode": 0, "message": "%u041F%u043E%20%u0434%u0430%u043D%u043D%u043E%u0439%20%u043E%u043F%u043B%u0430%u0442%u0435%20%u0432%u043E%u0437%u0432%u0440%u0430%u0442%u044B%20%u043D%u0435%20%u043D%u0430%u0439%u0434%u0435%u043D%u044B" }
Декодирование значения поля «message» - «По данной оплате возвраты не найдены».
- •
400 Bad Request
{ "ErrorCode":"Код ответа", "message":"Расшифровка кода ответа" }
7. Нотификация о финальном статусе возврата по динамическому QR-коду
Запрос отправляется из ПШ Банка во внутреннюю систему ТСП на URL адрес, указанный в параметре «queryData.notificationUrl» при направлении запроса «QRCreversal».
Метод «b2c-refund/notification»
a) Описание параметров запроса:
| Код ключа | Тип данных | required | Назначение |
|---|---|---|---|
| command | String (an-1…50) | y | Тип запроса. Константа «b2c-refund/notification» |
| messageID | String (ans-1024) | o | Уникальный идентификатор сообщения, GUID |
| TermNo | String (an-20) | y | Уникальный идентификатор терминала |
| originalQrcId | String (an-32) | y | Идентификатор зарегистрированной Платежной ссылки СБП, по которому была выполнена исходная Операция СБП C2B |
| originalTrxId | String (an-32) | y | Идентификатор исходной Операции СБП C2B |
| trxId | String (an-32) | y | Идентификатор Операции СБП B2C по сценарию «Возврат по Операции СБП C2B» |
| trxDT | String (n-14) | y | Дата и время выполнения Операции СБП B2C по сценарию «Возврат по Операции СБП C2B» (ГГГГММДДччммсс) |
| status | String (an-4) | y | Финальный статус Операции СБП B2C: «ACWP» — ACCEPTED операция завершена успешно; «RJCT» — REJECTED операция отклонена; |
| amount | Number | y | Сумма операции в копейках |
| ErrorCode | String (an-20) | y | Код ответа* |
| message | String (ans-1024) | y | Расшифровка кода ответа** |
| payerId | String (an-15) | y | Маскированный номер телефона Клиента-Получателя (Плательщика в исходной Операции C2B, кому делается возврат) |
| agentRefundRequestId | String (an-32) | y | Уникальный идентификатор запроса, назначаемый ТСП или Агентом ТСП |
| opkcRefundRequestId | String (an-32) | y | Уникальный идентификатор запроса на возврат, назначенный ОПКЦ СБП |
*, ** Таблица возможных кодов ответа приведена в приложении 2.
b) Примерный формат запроса (по успешному возврату):
1{ 2"command":"b2c-refund/notification", 3"messageID":" message", 4"TermNo":"90080567", 5"originalQrcId":"AS1000670LSS7DN18SJQDNP4B05KLJL2", 6"originalTrxId":"X1A2S3D5F6G7H8J9K0C4S5C6D7V5D1K2", 7"trxId":" A3024113609260070000086B8426B817", 8"trxDT":"20230624143642", 9"status":"ACWP", 10"amount":"10000", 11"ErrorCode":"0", 12"message":"OK", 13"payerId":"*********1234", 14"agentRefundRequestId":"00000000000000000182_abcd1994383", 15"opkcRefundRequestId":"BR10000OKEISOIPM8ST8TBLQHIN9R185" 16}
В ответ ожидается:
- •
http-код «200» — Успешный ответ (Уведомление получено);
- •
http-код «500» — Внутренняя ошибка.
c) Примерный формат запроса (по отклоненному возврату):
1{ 2"command":"b2c-refund/notification", 3"TermNo":"90080567", 4"originalQrcId":"AS1000670LSS7DN18SJQDNP4B05KLJL2", 5"originalTrxId":"X1A2S3D5F6G7H8J9K0C4S5C6D7V5D1K2", 6"trxId":"A3024113609260070000086B8426B817", 7"trxDT":"20230624143642", 8"status":"RJCT", 9"amount":"10000", 10"ErrorCode":"0", 11"message":"OK", 12"payerId":"*********1234" 13}
В ответ ожидается:
- •
http-код «200» — Успешный ответ (Уведомление получено);
- •
http-код «500» — Внутренняя ошибка.
d) ВС ТСП отвечает http-кодом «200» — успешное получение нотификации, или ошибкой.
В настоящий момент ответ ВС не обрабатывается шлюзом Агента ТСП. Обработка ответов ТСП находится в разработке.
В случае добавления со стороны НСПК дополнительных параметров уведомления, система, принимающая их от шлюза Альфа-Банка, не должна рассматривать такие неожиданные параметры как ошибочный запрос.